home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / mgn.com / MGN.DOC < prev    next >
Encoding:
Text File  |  1989-04-15  |  10.8 KB  |  252 lines
  1.  
  2.     MODEST MENGINE (MGN.EXE) { (c) April, 1989 by Ed Keefe,  
  3.                                CIS 73277,1064] and, hereby, placed 
  4.                                in  the public domain.}
  5.  
  6.                                PURPOSE
  7.  
  8.     MGN is a Menu Engine. It contains most of the logic to put a 
  9.     simple, light-bar menu on the screen. You provide an ASCII 
  10.     text file with the data for the menu engine. You also provide 
  11.     a a suitable batch file that will use the MGN program.
  12.  
  13.                       TYPICAL COMMAND TO RUN MGN
  14.  
  15.            MGN MNU.FIL
  16.  
  17.     where MNU.FIL is an an ASCII text file containing  one to ten 
  18.     lines with the following format.
  19.  
  20.     H|V Row Column ItemWord_0[*] ItemWord-1[*]...ItemWord_9 ExitWord
  21.  
  22.     where "H|V" indicates a Horizontal or Vertical (sub)menu
  23.  
  24.     "Row Column" are numbers indicating where to display the menu
  25.  
  26.     "ItemWord-n[*]" is a word describing an option in the menu. If 
  27.     the word contains an asterisk, MGN will assume that this 
  28.     ItemWord will call for a submenu. 
  29.  
  30.                              LIMITATIONS
  31.  
  32.     MGN is modest. It does not contain extensive error trapping.
  33.     It does not use the EXEC() operator, nor does the program 
  34.     terminate and stay resident.
  35.     
  36.     It has been designed and tested for menu systems containing a 
  37.     main menu and, at most, one sublevel of menus. Both the main 
  38.     and sub menus may contain, at most, ten options. MGN produces 
  39.     either 1-2-3 or Borland style menus. In its present form, MGN 
  40.     produces a DOS errorlevel number corresponding to the item in
  41.     the menu. This DOS errorlevel number can be tested within a 
  42.     batch file. (A sample batch file, "M.BAT", is included in this 
  43.     suite of files).
  44.  
  45.     Users of Turbo Pascal 4/5 are encouraged to enhance the MGN 
  46.     program. Source code is provided. MGN is placed in the public 
  47.     domain. You may freely copy and distribute the program in part 
  48.     or whole. If you use most, or all of the code in MGN in a 
  49.     program that you distribute, then intellectual honesty 
  50.     suggests that you include a reference to the original code, 
  51.     and its author, in  your program.  
  52.     
  53.     Support for MGN is also very modest. There is no quarantee 
  54.     with the program. MGN, and its attendant files,  are offered 
  55.     as-is. It is up to the user to determine if MGN is suitable 
  56.     for use and, if not, to make it suitable.
  57.     
  58.  
  59.                             HOW TO USE MGN
  60.  
  61.     Running the sample program.
  62.  
  63.     Extract MGN.EXE, MGN.MNU, M.BAT and QUIT.BAT from this 
  64.     archived file.
  65.  
  66.     At the DOS prompt, type M and press Return. 
  67.  
  68.     Provided you are using a color  monitor, the main menu will 
  69.     appear on row 10 of the monitor. The menu is coded for yellow 
  70.     letters on a brown background. The lighbar is coded for black 
  71.     letters on a lightgray background. It is a "horizontal" menu, 
  72.     a la 1-2-3. 
  73.  
  74.     You may exit the main menu by pressing ESC or by moving the 
  75.     lightbar to [ Exit ] and pressing Return.
  76.  
  77.     You may move the lightbar to the right or left with the right 
  78.     and left arrow keys. The up and down arrow keys will work 
  79.     equally well. The PgUp and Home keys will move the light bar 
  80.     to the first option in the menu. The PgDn and End keys will 
  81.     move the lightbar to the end of the menu. You may also press 
  82.     the first letter in a word to hop to that word. The lightbar 
  83.     will wrap around at either end of the menu.
  84.  
  85.     To activate a choice, press the Return key. 
  86.  
  87.     Some other lightbar menus will activate the choice when you 
  88.     press a letter. MGN forces you to use the Return key to 
  89.     confirm your choice. The advantage is that you may have 
  90.     several words with the same first letter in a submenu. 
  91.     Pressing that same letter will move the lightbar to another 
  92.     option. Try pressing and holding E in the main menu or W in 
  93.     the Editor* submenu of the sample menu.
  94.  
  95.     If the highlighted word ends with an asterisk, it means that 
  96.     this option will produce a submenu. If the word does not end 
  97.     with an asterisk, then pressing the Return key will let you 
  98.     quit the MGN program and return to the batch file.
  99.  
  100.     The sample MGN program produces a couple of pull-down, 
  101.     vertical submenus, a pull-up, vertical menu and a horizontal 
  102.     submenu. All of these appear to be attached to the main menu. 
  103.     They could just as well have been placed anywhere on the 
  104.     screen.
  105.  
  106.     When you are in a submenu, pressing ESC or moving the lightbar 
  107.     to one of the exit words and pressing Return, will move you 
  108.     back to the main menu. Pressing Return on any other word in a 
  109.     submenu program will halt the program's operation and return 
  110.     you to the batch file. 
  111.  
  112.                 DESIGNING YOUR OWN MENU DATA FILE.
  113.  
  114.     Here is a copy of the  sample MGN.MNU file for discussion purposes.
  115.  
  116.     H  10 8 Spreadsheets* Editors* Calculators*  Programming*  Help Exit
  117.     v 11 8 Quattro 1-2-3 AsEasyAs Quit
  118.     v 11 23 Sprint WordPerfect WordStar VideoDispEd MicroStar Return
  119.     V 6  33 PopCalc 41Emulator HP-12C Quit
  120.     h 11 8 Pascal TASM TurboC Prolog Quit
  121.  
  122.     The first line of the MGN.MNU file contains the specifications 
  123.     for the main menu. Subsequent lines contain the specifications 
  124.     for the submenus. The second line contains the submenu choices 
  125.     corresponding to the first ItemWord in the main menu (Spread- 
  126.     sheets): the third line contains the submenu choices for the 
  127.     second ItemWord in the main menu, and so on.
  128.  
  129.     The first character in each line must be either H or V. Upper 
  130.     or lower case is acceptable. The second and third items are 
  131.     the row and column where you wish the menu to appear on the 
  132.     screen. The range of values are 1..25, 1..80, respectively. 
  133.     You may have to experiment with different values to prevent 
  134.     wraparound on the screen. There is no error trapping in the 
  135.     MGN program to prevent wraparound at the edges of the screen.
  136.  
  137.     The individual words indicate choices. The space is used as a 
  138.     delimiter. So, if you want to use the phrase MY DICTIONARY as 
  139.     an option, use either MyDictionary or MY-DICTIONARY. 
  140.     
  141.     ItemWords, longer than 15 characters, will be truncated.
  142.  
  143.     If a word ends with an asterisk, MGN will try to hook it up 
  144.     with a submenu. If there is no such submenu, the program may 
  145.     hang and you will have to use CTRL-Break to quit. 
  146.  
  147.                DESIGNING A BATCH FILE THAT USES MGN.EXE
  148.  
  149.     The M.BAT file is a sample batch file that uses MGN. Here is 
  150.     the first part of that file.
  151.  
  152.     echo off
  153.     cls
  154.     MGN MGN.MNU
  155.     for %%e in (4 10 11 12 20 21 22 23 24 25) do if errorlevel=%%e SET opt=%%e
  156.     for %%e in (30 31 32 40 41 42 43 255) do if errorlevel=%%e SET opt=%%e
  157.     goto %opt%
  158.     :255
  159.     quit
  160.     :43
  161.     echo Pretending to use Prolog
  162.     quit
  163.     .
  164.     .
  165.     .
  166.     etc
  167.  
  168.     The third line in the batch file calls the MGN  program with 
  169.     the MGN.MNU file as a parameter.
  170.  
  171.     When MGN halts, it leaves behind an errorlevel number. The 
  172.     third and fourth lines test this errorlevel number. If the 
  173.     errorlevel is contained in the set of numbers inside the 
  174.     parentheses, then a DOS Environment variable (OPT) is SET to 
  175.     that errorlevel number. The fifth line fetches this number 
  176.     from the environment space and uses it to branch to the 
  177.     appropriate label in the batch file. Granted, this may appear 
  178.     obtuse and obfuscating, but these three lines take the place 
  179.     of at least 18 lines of the "If Errorlevel ==  " variety in a 
  180.     batch file. The multiple "quit" commands in the M.BAT file 
  181.     call the QUIT.BAT file. This is a quick and dirty way to exit 
  182.     from a long batch file. 
  183.     
  184.     There is no error trap to account for insufficient DOS 
  185.     environment space. 
  186.  
  187.     To determine which errorlevel numbers to use, follow these 
  188.     rules.
  189.     a. In the main menu, the errorlevel numbers range from 0 to 9
  190.        corresponding to the zeroth, first,...,ninth items (ten 
  191.        items in all.) Do NOT test for an errorlevel number, if 
  192.        that number corresponds to a starred (*) item. 
  193.     b. In the submenus, the errorlevel numbers range from 10 to 19 
  194.        for the first submenu: 20 to 29 for the second submenu,etc.
  195.        Theoretically you could have up to 10 main choices and 80 
  196.        subchoices (not counting the Exit prompts.) In practice,
  197.        this would be clumsy.
  198.     c. The last item in the main menu and each submenu should be 
  199.        an Exit word (pick your favorite.) 
  200.     d. Test for the Exit word with the errorlevel number 255.
  201.  
  202.                           MODIFYING MGN.PAS
  203.     
  204.     MGN (MenuEngine) comes with complete source code. Feel free to 
  205.     experiment with this. You will need Turbo Pascal 4 or 5 to 
  206.     recompile it. 
  207.     
  208.     The code is pretty straight-forward, I think. There are no 
  209.     nested functions or procedures. The trickiest part in the 
  210.     code is the use of the paramstr() and paramcount operators to 
  211.     parse a line of text. This technique comes from the mind of 
  212.     Neil Rubenking.
  213.  
  214.     Several suggested modifications are included at the end of the 
  215.     source code file.  
  216.     
  217.     #END#
  218.          ----------------end-of-author's-documentation---------------
  219.  
  220.                         Software Library Information:
  221.  
  222.                    This disk copy provided as a service of
  223.  
  224.                         The Public (Software) Library
  225.  
  226.          We are not the authors of this program, nor are we associated
  227.          with the author in any way other than as a distributor of the
  228.          program in accordance with the author's terms of distribution.
  229.  
  230.          Please direct shareware payments and specific questions about
  231.          this program to the author of the program, whose name appears
  232.          elsewhere in  this documentation. If you have trouble getting
  233.          in touch with the author,  we will do whatever we can to help
  234.          you with your questions. All programs have been tested and do
  235.          run.  To report problems,  please use the form that is in the
  236.          file PROBLEM.DOC on many of our disks or in other written for-
  237.          mat with screen printouts, if possible.  The P(s)L cannot de-
  238.          bug programs over the telephone.
  239.  
  240.          Disks in the P(s)L are updated monthly, so if you did not get
  241.          this disk  directly from the P(s)L,  you should be aware that
  242.          the files in this set may no  longer be the current versions.
  243.  
  244.          For a copy of the latest monthly software library newsletter
  245.          and a list of the 1,800+ disks in the library, call or write
  246.  
  247.                         The Public (Software) Library
  248.                               P.O.Box 35705 - F
  249.                            Houston, TX 77235-5705
  250.                                (713) 665-7017
  251.  
  252.